<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>

    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta content="Cask Data, Inc." name="author" />
<meta content="HTTP RESTful Interface to the Cask Data Application Platform" name="description" />
<meta content="Copyright © 2014-2017 Cask Data, Inc." name="copyright" />


    <meta name="git_release" content="6.1.1">
    <meta name="git_hash" content="05fbac36f9f7aadeb44f5728cea35136dbc243e5">
    <meta name="git_timestamp" content="2020-02-09 08:22:47 +0800">
    <title>Query HTTP RESTful API</title>

    <link rel="stylesheet" href="../_static/cdap-bootstrap.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/bootstrap-3.3.6/css/bootstrap.min.css" type="text/css" />
    <link rel="stylesheet" href="../_static/bootstrap-3.3.6/css/bootstrap-theme.min.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/bootstrap-sphinx.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/cdap-dynamicscrollspy-4.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/jquery.mCustomScrollbar.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/cdap-jquery.mCustomScrollbar.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/abixTreeList-2.css" type="text/css" />
    <link rel="stylesheet" href="../_static/cdap-bootstrap.css" type="text/css" />

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '6.1.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>

    <link rel="shortcut icon" href="../_static/favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="top" title="Cask Data Application Platform 6.1.1 Documentation" href="../index.html" />
    <link rel="up" title="CDAP HTTP RESTful API v3" href="index.html" />
    <link rel="next" title="Reports HTTP RESTful API" href="reports.html" />
    <link rel="prev" title="Profile HTTP RESTful API" href="profile.html" />
    <!-- block extrahead -->
    <meta charset='utf-8'>
    <meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
    <meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
    <meta name="apple-mobile-web-app-capable" content="yes">
    <!-- block extrahead end -->

</head>
<body role="document">

<!-- block navbar -->
<div id="navbar" class="navbar navbar-inverse navbar-default navbar-fixed-top">
    <div class="container-fluid">
      <div class="row">
        <div class="navbar-header">
          <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
          <a class="navbar-brand" href="../table-of-contents/../../index.html">
            <span><img alt="CDAP logo" src="../_static/cdap_logo.svg"/></span>
          </a>

          <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
          </button>

          <div class="pull-right">
            <div class="dropdown version-dropdown">
              <a href="#" class="dropdown-toggle" data-toggle="dropdown"
                role="button" aria-haspopup="true" aria-expanded="false">
                v 6.1.1 <span class="caret"></span>
              </a>
              <ul class="dropdown-menu">
                <li><a href="//docs.cdap.io/cdap/5.1.2/en/index.html">v 5.1.2</a></li>
                <li><a href="//docs.cdap.io/cdap/4.3.4/en/index.html">v 4.3.4</a></li>
              </ul>
            </div>
          </div>
          <form class="navbar-form navbar-right navbar-search" action="../search.html" method="get">
            <div class="form-group">
              <div class="navbar-search-image material-icons"></div>
              <input type="text" name="q" class="form-control" placeholder="  Search" />
            </div>
            <input type="hidden" name="check_keywords" value="yes" />
            <input type="hidden" name="area" value="default" />
          </form>

          <div class="collapse navbar-collapse nav-collapse navbar-right navbar-navigation">
            <ul class="nav navbar-nav"><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../index.html">简介</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../guides.html">手册</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link current" href="../table-of-contents/../../reference-manual/index.html">参考</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../faqs/index.html">帮助</a></li>
            </ul>
          </div>

        </div>
      </div>
    </div>
  </div><!-- block navbar end -->
<!-- block main content -->
<div class="main-container container">
  <div class="row"><div class="col-md-2">
      <div id="sidebar" class="bs-sidenav scrollable-y-outside" role="complementary">
<!-- theme_manual: reference-manual -->
<!-- theme_manual_highlight: reference -->
<!-- sidebar_title_link: Reference -->

  <div role="note" aria-label="manuals links"><h3>Reference</h3>
    <ul class="reference-page-menu">
      <nav class="pagenav">
      <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../index.html"> Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../characters.html"> Supported Characters</a></li>
<li class="toctree-l1"><a class="reference internal" href="../cli-api.html"> Command Line Interface API</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html"> HTTP RESTful API</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="introduction.html">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="artifact.html">Artifact</a></li>
<li class="toctree-l2"><a class="reference internal" href="configuration.html">Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="dataset.html">Dataset</a></li>
<li class="toctree-l2"><a class="reference internal" href="lifecycle.html">Lifecycle</a></li>
<li class="toctree-l2"><a class="reference internal" href="logging.html">Logging</a></li>
<li class="toctree-l2"><a class="reference internal" href="metadata.html">Metadata</a></li>
<li class="toctree-l2"><a class="reference internal" href="metrics.html">Metrics</a></li>
<li class="toctree-l2"><a class="reference internal" href="monitor.html">Monitor</a></li>
<li class="toctree-l2"><a class="reference internal" href="namespace.html">Namespace</a></li>
<li class="toctree-l2"><a class="reference internal" href="dashboard.html">Dashboard</a></li>
<li class="toctree-l2"><a class="reference internal" href="preferences.html">Preferences</a></li>
<li class="toctree-l2"><a class="reference internal" href="profile.html">Profile</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Query</a></li>
<li class="toctree-l2"><a class="reference internal" href="reports.html">Reports</a></li>
<li class="toctree-l2"><a class="reference internal" href="security.html">Security</a></li>
<li class="toctree-l2"><a class="reference internal" href="service.html">Service</a></li>
<li class="toctree-l2"><a class="reference internal" href="transactions.html">Transactions</a></li>
<li class="toctree-l2"><a class="reference internal" href="workflow.html">Workflow</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../java-client-api.html"> Java Client API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../javadocs/index.html"> Javadocs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../release-notes.html"> 发行说明</a></li>
<li class="toctree-l1"><a class="reference internal" href="../licenses/index.html"> Trademarks, Licenses, and Dependencies</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html"> 术语表</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html"> Index</a></li>
</ul>
</nav>
    </ul>
  </div></div>
    </div><div class="col-md-8 content" id="main-content">
    
  <div class="section" id="query-http-restful-api">
<span id="http-restful-api-query"></span><h1>Query HTTP RESTful API<a class="headerlink" href="#query-http-restful-api" title="Permalink to this headline">🔗</a></h1>
<p>Use the CDAP Query HTTP RESTful API to submit SQL-like queries over datasets. Queries are
processed asynchronously; to obtain query results, perform these steps:</p>
<ul class="simple">
<li>first, <strong>submit</strong> the query;</li>
<li>then poll for the query’s <strong>status</strong> until it is finished;</li>
<li>once finished, retrieve the <strong>result schema</strong> and the <strong>results</strong>;</li>
<li>finally, <strong>close the query</strong> to free the resources that it holds.</li>
</ul>
<p>Additional details on querying can be found in the <a class="reference external" href="../../../developer-manual/data-exploration/index.html#data-exploration" title="(in Cask Data Application Platform v6.1.1)"><span class="xref std std-ref">开发手册: Data
Exploration</span></a>.</p>
<p>All methods or endpoints described in this API have a base URL (typically
<code class="docutils literal notranslate"><span class="pre">http://&lt;host&gt;:11015</span></code> or <code class="docutils literal notranslate"><span class="pre">https://&lt;host&gt;:10443</span></code>) that precedes the resource
identifier, as described in the <a class="reference internal" href="introduction.html#http-restful-api-conventions-base-url"><span class="std std-ref">RESTful API Conventions</span></a>.
These methods return a status code, as listed in the <a class="reference internal" href="introduction.html#http-restful-api-status-codes"><span class="std std-ref">RESTful API  Status Codes</span></a>.</p>
<div class="section" id="submitting-a-query">
<span id="http-restful-api-query-submitting"></span><h2>Submitting a Query<a class="headerlink" href="#submitting-a-query" title="Permalink to this headline">🔗</a></h2>
<p>To submit a SQL query, post the query string to the <code class="docutils literal notranslate"><span class="pre">queries</span></code> URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/data/explore/queries</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
</tbody>
</table>
<p>The body of the request must contain a JSON string of the form:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
  <span class="nt">&quot;query&quot;</span><span class="p">:</span> <span class="s2">&quot;&lt;SQL-query-string&gt;&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>where <code class="docutils literal notranslate"><span class="pre">SQL-query-string</span></code> is the actual SQL query.
If you are running a version of Hive that uses reserved keywords, and a column in your query is a <a class="reference external" href="https://cwiki.apache.org/confluence/display/Hive/LanguageManual+DDL#LanguageManualDDL-Keywords,Non-reservedKeywordsandReservedKeywords">Hive reserved keyword</a>, you must enclose the column name in backticks.</p>
<p>For example:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
  <span class="nt">&quot;query&quot;</span><span class="p">:</span> <span class="s2">&quot;select `date` from stream_events&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>The query execution was successfully initiated, and the body will contain the query-handle
used to identify the query in subsequent requests</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">400</span> <span class="pre">Bad</span> <span class="pre">Request</span></code></td>
<td>The query is not well-formed or contains an error, such as a nonexistent table name</td>
</tr>
</tbody>
</table>
<p class="rubric">Comments</p>
<p>If the query execution was successfully initiated, the body of the
response will contain a handle that can be used to identify the query in
subsequent requests:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span> <span class="nt">&quot;handle&quot;</span><span class="p">:</span> <span class="s2">&quot;&lt;query-handle&gt;&quot;</span> <span class="p">}</span>
</pre></div>
</div>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Request</th>
<td><code class="docutils literal notranslate"><span class="pre">PUT</span> <span class="pre">/v3/namespaces/default/data/explore/queries</span></code></td>
</tr>
<tr class="row-even"><th class="stub">HTTP Body</th>
<td><code class="docutils literal notranslate"><span class="pre">{&quot;query&quot;:&quot;SELECT</span> <span class="pre">*</span> <span class="pre">FROM</span> <span class="pre">dataset_mydataset</span> <span class="pre">LIMIT</span> <span class="pre">5&quot;}</span></code></td>
</tr>
<tr class="row-odd"><th class="stub">HTTP Response</th>
<td><code class="docutils literal notranslate"><span class="pre">{&quot;handle&quot;:&quot;57cf1b01-8dba-423a-a8b4-66cd29dd75e2&quot;}</span></code></td>
</tr>
<tr class="row-even"><th class="stub">Description</th>
<td>Submit a query in the namespace <em>default</em> to get the first 5 entries from the
dataset, <em>mydataset</em> in the namespace <em>default</em></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="status-of-a-query">
<span id="http-restful-api-query-status"></span><h2>Status of a Query<a class="headerlink" href="#status-of-a-query" title="Permalink to this headline">🔗</a></h2>
<p>The status of a query is obtained using a HTTP GET request to the query’s URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/data/explore/queries/&lt;query-handle&gt;/status</span>
</pre></div>
</div>
<p><strong>Note:</strong> this endpoint is <em>not</em> namespaced, as all query-handles are globally unique.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">query-handle</span></code></td>
<td>Handle obtained when the query was submitted</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>The query exists and the body contains its status</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code></td>
<td>The query handle does not match any current query</td>
</tr>
</tbody>
</table>
<p class="rubric">Comments</p>
<p>If the query exists, the body will contain the status of its execution
and whether the query has a results set:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">{</span>
<span class="go">  &quot;status&quot;: &quot;&lt;status-code&gt;&quot;,</span>
<span class="go">  &quot;hasResults&quot;: &lt;boolean&gt;</span>
<span class="go"> }</span>
</pre></div>
</div>
<p>Status can be one of the following: <code class="docutils literal notranslate"><span class="pre">INITIALIZED</span></code>, <code class="docutils literal notranslate"><span class="pre">RUNNING</span></code>, <code class="docutils literal notranslate"><span class="pre">FINISHED</span></code>, <code class="docutils literal notranslate"><span class="pre">CANCELED</span></code>, <code class="docutils literal notranslate"><span class="pre">CLOSED</span></code>,
<code class="docutils literal notranslate"><span class="pre">ERROR</span></code>, <code class="docutils literal notranslate"><span class="pre">UNKNOWN</span></code>, and <code class="docutils literal notranslate"><span class="pre">PENDING</span></code>.</p>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Request</th>
<td><code class="docutils literal notranslate"><span class="pre">GET</span> <span class="pre">/v3/data/explore/queries/57cf1b01-8dba-423a-a8b4-66cd29dd75e2/status</span></code></td>
</tr>
<tr class="row-even"><th class="stub">HTTP Response</th>
<td><code class="docutils literal notranslate"><span class="pre">{&quot;status&quot;:&quot;FINISHED&quot;,&quot;hasResults&quot;:true}</span></code></td>
</tr>
<tr class="row-odd"><th class="stub">Description</th>
<td>Retrieve the status of the query in the namespace <em>default</em> which has the handle
<code class="docutils literal notranslate"><span class="pre">57cf1b01-8dba-423a-a8b4-66cd29dd75e2</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="obtaining-the-result-schema">
<span id="http-restful-api-query-obtaining-results"></span><h2>Obtaining the Result Schema<a class="headerlink" href="#obtaining-the-result-schema" title="Permalink to this headline">🔗</a></h2>
<p>If the query’s status is <code class="docutils literal notranslate"><span class="pre">FINISHED</span></code> and it has results, you can obtain the schema of the results:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/data/explore/queries/&lt;query-handle&gt;/schema</span>
</pre></div>
</div>
<p><strong>Note:</strong> this endpoint is <em>not</em> namespaced, as all query-handles are globally unique.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">query-handle</span></code></td>
<td>Handle obtained when the query was submitted</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>The query was successfully received and the query schema was returned in the body</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">400</span> <span class="pre">Bad</span> <span class="pre">Request</span></code></td>
<td>The query is not well-formed or contains an error, or the query status is not <code class="docutils literal notranslate"><span class="pre">FINISHED</span></code></td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code></td>
<td>The query handle does not match any current query</td>
</tr>
</tbody>
</table>
<p class="rubric">Comments</p>
<p>The query’s result schema is returned in a JSON body as a list of columns,
each given by its name, type and position; if the query has no result set, this list is empty:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">[</span>
<span class="go">  {&quot;name&quot;: &quot;&lt;name&gt;&quot;, &quot;type&quot;: &quot;&lt;type&gt;&quot;, &quot;position&quot;: &lt;int&gt;},</span>
<span class="go">  ...</span>
<span class="go">]</span>
</pre></div>
</div>
<p>The type of each column is a data type as defined in the <a class="reference external" href="https://cwiki.apache.org/confluence/display/Hive/LanguageManual+DDL">Hive language manual</a>.</p>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Request</th>
<td><code class="docutils literal notranslate"><span class="pre">GET</span> <span class="pre">/v3/namespaces/default/data/explore/queries/57cf1b01-8dba-423a-a8b4-66cd29dd75e2/schema</span></code></td>
</tr>
<tr class="row-even"><th class="stub">HTTP Response</th>
<td><code class="docutils literal notranslate"><span class="pre">[{&quot;name&quot;:&quot;dataset_mydataset.key&quot;,&quot;type&quot;:&quot;array&lt;tinyint&gt;&quot;,&quot;position&quot;:1},</span></code>
<code class="docutils literal notranslate"><span class="pre">{&quot;name&quot;:&quot;dataset_mydataset.value&quot;,&quot;type&quot;:&quot;array&lt;tinyint&gt;&quot;,&quot;position&quot;:2}]</span></code></td>
</tr>
<tr class="row-odd"><th class="stub">Description</th>
<td>Retrieve the schema of the result of the query in the namespace <em>default</em> which has
the handle <code class="docutils literal notranslate"><span class="pre">57cf1b01-8dba-423a-a8b4-66cd29dd75e2</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="retrieving-query-results">
<span id="http-restful-api-query-retrieving-results"></span><h2>Retrieving Query Results<a class="headerlink" href="#retrieving-query-results" title="Permalink to this headline">🔗</a></h2>
<p>Query results can be retrieved in batches after the query is finished, optionally specifying the batch
size in the body of the request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/data/explore/queries/&lt;query-handle&gt;/next</span>
</pre></div>
</div>
<p><strong>Note:</strong> this endpoint is <em>not</em> namespaced, as all query-handles are globally unique.</p>
<p>The body of the request can contain a JSON string specifying the batch size:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">{</span>
<span class="go">  &quot;size&quot;: &lt;int&gt;</span>
<span class="go">}</span>
</pre></div>
</div>
<p>If the batch size is not specified, the default is 20.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">query-handle</span></code></td>
<td>Handle obtained when the query was submitted</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>The event was successfully received and the result of the query was returned in the body</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code></td>
<td>The query handle does not match any current query</td>
</tr>
</tbody>
</table>
<p class="rubric">Comments</p>
<p>The results are returned in a JSON body as a list of columns,
each given as a structure containing a list of column values:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">[</span>
<span class="go">  { &quot;columns&quot;: [ &lt;value-1&gt;, &lt;value-2&gt;, ..., ] },</span>
<span class="go">  ...</span>
<span class="go">]</span>
</pre></div>
</div>
<p>The value at each position has the type that was returned in the result schema for that position.
For example, if the returned type was <code class="docutils literal notranslate"><span class="pre">INT</span></code>, then the value will be an integer literal,
whereas for <code class="docutils literal notranslate"><span class="pre">STRING</span></code> or <code class="docutils literal notranslate"><span class="pre">VARCHAR</span></code> the value will be a string literal.</p>
<p>Repeat the query to retrieve subsequent results. If all results of the query have already
been retrieved, then the returned list is empty.</p>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Request</th>
<td><code class="docutils literal notranslate"><span class="pre">POST</span> <span class="pre">/v3/namespaces/default/data/explore/queries/57cf1b01-8dba-423a-a8b4-66cd29dd75e2/next</span></code></td>
</tr>
<tr class="row-even"><th class="stub">HTTP Response</th>
<td><div class="first last line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">[</span></code></div>
<div class="line"><code class="docutils literal notranslate">&#160; <span class="pre">{&quot;columns&quot;:</span> <span class="pre">[10,</span> <span class="pre">5]},</span></code></div>
<div class="line"><code class="docutils literal notranslate">&#160; <span class="pre">{&quot;columns&quot;:</span> <span class="pre">[</span> <span class="pre">20,</span> <span class="pre">27]},</span></code></div>
<div class="line"><code class="docutils literal notranslate">&#160; <span class="pre">{&quot;columns&quot;:</span> <span class="pre">[</span> <span class="pre">50,</span> <span class="pre">6]},</span></code></div>
<div class="line"><code class="docutils literal notranslate">&#160; <span class="pre">{&quot;columns&quot;:</span> <span class="pre">[</span> <span class="pre">90,</span> <span class="pre">30]},</span></code></div>
<div class="line"><code class="docutils literal notranslate">&#160; <span class="pre">{&quot;columns&quot;:</span> <span class="pre">[</span> <span class="pre">95,</span> <span class="pre">91]}</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">]</span></code></div>
</div>
</td>
</tr>
<tr class="row-odd"><th class="stub">Description</th>
<td>Retrieve the results of the query which has the handle 57cf1b01-8dba-423a-a8b4-66cd29dd75e2</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="closing-a-query">
<span id="http-restful-api-query-closing"></span><h2>Closing a Query<a class="headerlink" href="#closing-a-query" title="Permalink to this headline">🔗</a></h2>
<p>The query can be closed by issuing an HTTP DELETE against its URL:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">DELETE /v3/data/explore/queries/&lt;query-handle&gt;</span>
</pre></div>
</div>
<p>This frees all resources that are held by this query.</p>
<p><strong>Note:</strong> this endpoint is <em>not</em> namespaced, as all query-handles are globally unique.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">query-handle</span></code></td>
<td>Handle obtained when the query was submitted</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>The query was closed</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">400</span> <span class="pre">Bad</span> <span class="pre">Request</span></code></td>
<td>The query was not in a state that could be closed; either wait until it is finished, or cancel it</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code></td>
<td>The query handle does not match any current query</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Request</th>
<td><code class="docutils literal notranslate"><span class="pre">DELETE</span> <span class="pre">/v3/namespaces/default/data/explore/queries/57cf1b01-8dba-423a-a8b4-66cd29dd75e2</span></code></td>
</tr>
<tr class="row-even"><th class="stub">Description</th>
<td>Close the query in the namespace <em>default</em> which has the handle <code class="docutils literal notranslate"><span class="pre">57cf1b01-8dba-423a-a8b4-66cd29dd75e2</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="list-of-queries">
<span id="http-restful-api-query-listing"></span><h2>List of Queries<a class="headerlink" href="#list-of-queries" title="Permalink to this headline">🔗</a></h2>
<p>To return a list of queries, use:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/data/explore/queries?limit=&lt;limit&gt;&amp;cursor=&lt;cursor&gt;&amp;offset=&lt;offset&gt;</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">limit</span></code></td>
<td>Optional number indicating how many results to return in the response; by default, 50 results are returned</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">cursor</span></code></td>
<td>Optional string specifying if the results returned should be in the forward or reverse direction;
should be one of <code class="docutils literal notranslate"><span class="pre">next</span></code> or <code class="docutils literal notranslate"><span class="pre">prev</span></code></td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">offset</span></code></td>
<td>Optional offset for pagination; returns the results that are greater than offset if the cursor is <code class="docutils literal notranslate"><span class="pre">next</span></code> or
results that are less than offset if cursor is <code class="docutils literal notranslate"><span class="pre">prev</span></code></td>
</tr>
</tbody>
</table>
<p class="rubric">Comments</p>
<p>The results are returned as a JSON array, with each element containing information about a query:</p>
<div class="highlight-json-ellipsis notranslate"><div class="highlight"><pre><span></span><span class="p">[</span>
  <span class="p">{</span>
      <span class="nt">&quot;timestamp&quot;</span><span class="p">:</span> <span class="mi">1407192465183</span><span class="p">,</span>
      <span class="nt">&quot;statement&quot;</span><span class="p">:</span> <span class="s2">&quot;SHOW TABLES&quot;</span><span class="p">,</span>
      <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;FINISHED&quot;</span><span class="p">,</span>
      <span class="nt">&quot;query_handle&quot;</span><span class="p">:</span> <span class="s2">&quot;319d9438-903f-49b8-9fff-ac71cf5d173d&quot;</span><span class="p">,</span>
      <span class="nt">&quot;has_results&quot;</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
      <span class="nt">&quot;is_active&quot;</span><span class="p">:</span> <span class="kc">false</span>
  <span class="p">},</span>
  <span class="c">...</span>
<span class="p">]</span>
</pre></div>
</div>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Request</th>
<td><code class="docutils literal notranslate"><span class="pre">GET</span> <span class="pre">/v3/namespaces/default/data/explore/queries</span></code></td>
</tr>
<tr class="row-even"><th class="stub">HTTP Response</th>
<td><div class="first last line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">[</span> <span class="pre">{</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">&nbsp;&quot;timestamp&quot;:</span> <span class="pre">1411266478717,</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">&nbsp;&quot;statement&quot;:</span> <span class="pre">&quot;SELECT</span> <span class="pre">*</span> <span class="pre">FROM</span> <span class="pre">dataset_mydataset&quot;,</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">&nbsp;&quot;status&quot;:</span> <span class="pre">&quot;FINISHED&quot;,</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">&nbsp;&quot;query_handle&quot;:</span> <span class="pre">&quot;57cf1b01-8dba-423a-a8b4-66cd29dd75e2&quot;,</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">&nbsp;&quot;has_results&quot;:</span> <span class="pre">true,</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">&nbsp;&quot;is_active&quot;:</span> <span class="pre">false</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">}</span> <span class="pre">]</span></code></div>
</div>
</td>
</tr>
<tr class="row-odd"><th class="stub">Description</th>
<td>Retrieves all queries</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="count-of-active-queries">
<span id="http-restful-api-query-counting"></span><h2>Count of Active Queries<a class="headerlink" href="#count-of-active-queries" title="Permalink to this headline">🔗</a></h2>
<p>To return the count of <strong>active</strong> queries, use:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/data/explore/queries/count</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
</tbody>
</table>
<p>The results are returned in the body as a JSON string:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span> <span class="nt">&quot;count&quot;</span><span class="p">:</span><span class="mi">6</span> <span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="download-query-results">
<span id="http-restful-api-query-downloading"></span><h2>Download Query Results<a class="headerlink" href="#download-query-results" title="Permalink to this headline">🔗</a></h2>
<p>To download the results of a query, use:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/data/explore/queries/&lt;query-handle&gt;/download</span>
</pre></div>
</div>
<p>The results of the query are returned in CSV format.</p>
<p><strong>Note:</strong> this endpoint is <em>not</em> namespaced, as all query-handles are globally unique.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">query-handle</span></code></td>
<td>Handle obtained when the query was submitted or via a list of queries</td>
</tr>
</tbody>
</table>
<p class="rubric">Comments</p>
<p>The query results can be downloaded only once. The RESTful API will return a Status Code <code class="docutils literal notranslate"><span class="pre">409</span> <span class="pre">Conflict</span></code>
if results for the <code class="docutils literal notranslate"><span class="pre">query-handle</span></code> are attempted to be downloaded again.</p>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>The HTTP call was successful</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code></td>
<td>The query handle does not match any current query</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">409</span> <span class="pre">Conflict</span></code></td>
<td>The query results were already downloaded</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="enabling-and-disabling-querying">
<span id="http-restful-api-query-enable-disable"></span><h2>Enabling and Disabling Querying<a class="headerlink" href="#enabling-and-disabling-querying" title="Permalink to this headline">🔗</a></h2>
<p>Querying (or exploring) of datasets and streams can be enabled and disabled using these endpoints.</p>
<p>Exploration of data in CDAP is governed by a combination of enabling the CDAP Explore
Service and then creating datasets and streams that are explorable. The CDAP Explore
Service is enabled by a <a class="reference external" href="../../../admin-manual/appendices/cdap-site.html#appendix-cdap-default-explore-service" title="(in Cask Data Application Platform v6.1.1)"><span class="xref std std-ref">setting in the CDAP configuration file</span></a> (<code class="docutils literal notranslate"><span class="pre">explore.enabled</span></code> in <code class="docutils literal notranslate"><span class="pre">cdap-site.xml</span></code> file).</p>
<p>Datasets and streams—that were created while the Explore Service was not enabled—can, once the service is enabled and CDAP restarted, be enabled for exploration by
using these endpoints.</p>
<p>You can also use these endpoints to disable exploration of a specific dataset or
stream. The dataset or stream will still be accessible programmatically; it just won’t
respond to queries or be available for exploration using the CDAP UI.</p>
<p>For datasets:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/data/explore/datasets/&lt;dataset-name&gt;/enable</span>
<span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/data/explore/datasets/&lt;dataset-name&gt;/disable</span>
</pre></div>
</div>
<p>For streams:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/data/explore/streams/&lt;stream-name&gt;/tables/&lt;table-name&gt;/enable</span>
<span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/data/explore/streams/&lt;stream-name&gt;/tables/&lt;table-name&gt;/disable</span>
</pre></div>
</div>
<p>Each of these endpoints returns a query handle that can be used to submit requests
tracking the <a class="reference internal" href="#http-restful-api-query-status"><span class="std std-ref">status of the query</span></a>.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">dataset-name</span></code></td>
<td>Name of the dataset</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">stream-name</span></code></td>
<td>Name of the stream</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">table-name</span></code></td>
<td>Name of the table</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>The query execution was successfully initiated, and the body will contain the query-handle
used to identify the query in subsequent requests</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code></td>
<td>The query is not well-formed or contains an error such as a nonexistent table name</td>
</tr>
</tbody>
</table>
<p class="rubric">Comments</p>
<p>If the request was successful, the body will contain a query handle that can be used to
identify the query in subsequent requests, such as a <a class="reference internal" href="#http-restful-api-query-status"><span class="std std-ref">status request</span></a>:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span> <span class="nt">&quot;handle&quot;</span><span class="p">:</span> <span class="s2">&quot;&lt;query-handle&gt;&quot;</span> <span class="p">}</span>
</pre></div>
</div>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Request</th>
<td><code class="docutils literal notranslate"><span class="pre">POST</span> <span class="pre">/v3/namespaces/default/data/explore/datasets/logEventStream_converted/disable</span></code></td>
</tr>
<tr class="row-even"><th class="stub">HTTP Response</th>
<td><code class="docutils literal notranslate"><span class="pre">{&quot;handle&quot;:&quot;57cf1b01-8dba-423a-a8b4-66cd29dd75e2&quot;}</span></code></td>
</tr>
<tr class="row-odd"><th class="stub">Description</th>
<td>Submits a request in the namespace <em>default</em> to disable the dataset
<em>logEventStream_converted</em> from being explored. The handle can be used to check the
status.</td>
</tr>
</tbody>
</table>
</div>
</div>

</div>
    <div class="col-md-2">
      <div id="right-sidebar" class="bs-sidenav scrollable-y" role="complementary">
        <div id="localtoc-scrollspy">
        </div>
      </div>
    </div></div>
</div>
<!-- block main content end -->
<!-- block footer -->
<footer class="footer">
      <div class="container">
        <div class="row">
          <div class="col-md-2 footer-left"><a title="Profile HTTP RESTful API" href="profile.html" />Previous</a></div>
          <div class="col-md-8 footer-center"><a class="footer-tab-link" href="../table-of-contents/../../reference-manual/licenses/index.html">Copyright</a> &copy; 2014-2020 Cask Data, Inc.&bull; <a class="footer-tab-link" href="//docs.cask.co/cdap/6.1.1/cdap-docs-6.1.1-web.zip" rel="nofollow">Download</a> an archive or
<a class="footer-tab-link" href="//docs.cask.co/cdap">switch the version</a> of the documentation
          </div>
          <div class="col-md-2 footer-right"><a title="Reports HTTP RESTful API" href="reports.html" />Next</a></div>
        </div>
      </div>
    </footer>
<!-- block footer end -->
<script type="text/javascript" src="../_static/bootstrap-3.3.6/js/bootstrap.min.js"></script><script type="text/javascript" src="../_static/js/bootstrap-sphinx.js"></script><script type="text/javascript" src="../_static/js/abixTreeList-2.js"></script><script type="text/javascript" src="../_static/js/cdap-dynamicscrollspy-4.js"></script><script type="text/javascript" src="../_static/js/cdap-version-menu.js"></script><script type="text/javascript" src="../_static/js/copy-to-clipboard.js"></script><script type="text/javascript" src="../_static/js/jquery.mousewheel.min.js"></script><script type="text/javascript" src="../_static/js/jquery.mCustomScrollbar.js"></script><script type="text/javascript" src="../_static/js/js.cookie.js"></script><script type="text/javascript" src="../_static/js/tabbed-parsed-literal-0.2.js"></script><script type="text/javascript" src="../_static/js/cdap-onload-javascript.js"></script><script type="text/javascript" src="../_static/js/cdap-version-menu.js"></script>
    <script src="https://cdap.gitee.io/docs/cdap/json-versions.js"/></script>
  </body>
</html>